// Tool Interface Definitions

/**
 * 工具分类枚举
 */
export enum ToolCategory {
    FILE_OPERATIONS = 'file-operations',
    PROCESS_MANAGEMENT = 'process-management',
    WEB_OPERATIONS = 'web-operations',
    DIAGNOSTICS = 'diagnostics',
    TASK_MANAGEMENT = 'task-management',
    MEMORY_MANAGEMENT = 'memory-management',
    VISUALIZATION = 'visualization',
    CONTEXT_RETRIEVAL = 'context-retrieval',
    OTHER = 'other'
}

/**
 * 错误代码枚举
 */
export enum ErrorCode {
    TOOL_NOT_FOUND = 'TOOL_NOT_FOUND',
    INVALID_PARAMETERS = 'INVALID_PARAMETERS',
    EXECUTION_FAILED = 'EXECUTION_FAILED',
    PERMISSION_DENIED = 'PERMISSION_DENIED',
    TIMEOUT = 'TIMEOUT',
    TOOL_DISABLED = 'TOOL_DISABLED',
    INTERNAL_ERROR = 'INTERNAL_ERROR'
}

/**
 * 工具定义接口
 */
export interface ToolDefinition {
    name: string;
    description: string;
    category: ToolCategory;
    parameters: any[]; // Array of parameter definitions
    timeout?: number;
    requiresPermissions?: string[];
    isAsync: boolean;
    enabled?: boolean;
    version?: string;
    tags?: string[];
}

/**
 * 工具执行结果接口
 */
export interface ToolResult {
    success: boolean;
    data?: any;
    error?: {
        code: string;
        message: string;
        details?: any;
    };
    executionTime?: number; // 毫秒
    metadata?: Record<string, any>;
}

/**
 * 工具执行上下文接口
 */
export interface ToolExecutionContext {
    userId?: string;
    sessionId?: string;
    workspaceRoot: string;
    environment: Record<string, string>;
    timestamp: Date;
    requestId?: string;
    logger?: any;
    permissions?: string[];
}

/**
 * 工具处理器接口
 */
export interface ToolHandler {
    /**
     * 执行工具
     * @param parameters 工具参数
     * @param context 执行上下文
     * @returns 工具结果
     */
    execute(parameters: Record<string, any>, context: ToolExecutionContext): Promise<ToolResult>;

    /**
     * 验证参数
     * @param parameters 工具参数
     * @returns 验证结果
     */
    validate(parameters: Record<string, any>): ValidationResult;

    /**
     * 预处理参数
     * @param parameters 工具参数
     * @param context 执行上下文
     * @returns 处理后的参数
     */
    preprocessParameters?(parameters: Record<string, any>, context: ToolExecutionContext): Promise<Record<string, any>>;

    /**
     * 转换结果
     * @param result 原始结果
     * @returns 转换后的结果
     */
    transformResult?(result: any): Promise<any>;
}

/**
 * 验证结果接口
 */
export interface ValidationResult {
    isValid: boolean;
    errors: string[];
}

/**
 * 已注册工具接口
 */
export interface RegisteredTool {
    definition: ToolDefinition;
    handler: ToolHandler;
    metadata: {
        registeredAt: Date;
        callCount: number;
        lastCalled: Date | null;
        isEnabled: boolean;
    };
}

/**
 * 工具注册表接口
 */
export interface ToolRegistry {
    /**
     * 注册工具
     * @param toolName 工具名称
     * @param definition 工具定义
     * @param handler 工具处理器
     */
    register(toolName: string, definition: ToolDefinition, handler: ToolHandler): void;

    /**
     * 注销工具
     * @param toolName 工具名称
     */
    unregister(toolName: string): boolean;

    /**
     * 获取工具
     * @param toolName 工具名称
     * @returns 已注册工具
     */
    getTool(toolName: string): RegisteredTool | null;

    /**
     * 获取所有工具
     * @returns 已注册工具数组
     */
    getAllTools(): RegisteredTool[];

    /**
     * 按分类获取工具
     * @param category 工具分类
     * @returns 已注册工具数组
     */
    getToolsByCategory(category: ToolCategory): RegisteredTool[];

    /**
     * 更新调用统计
     * @param toolName 工具名称
     */
    updateCallStats(toolName: string): void;

    /**
     * 设置工具启用状态
     * @param toolName 工具名称
     * @param enabled 启用状态
     */
    setToolEnabled(toolName: string, enabled: boolean): boolean;

    /**
     * 获取工具统计信息
     * @param toolName 工具名称
     */
    getToolStats(toolName: string): any;

    /**
     * 清空所有工具
     */
    clear(): void;

    /**
     * 获取注册表大小
     */
    size(): number;
}

/**
 * 工具执行引擎接口
 */
export interface ToolExecutionEngine {
    /**
     * 执行工具
     * @param toolName 工具名称
     * @param parameters 工具参数
     * @param context 执行上下文
     * @returns 工具结果
     */
    execute(toolName: string, parameters: Record<string, any>, context?: ToolExecutionContext): Promise<ToolResult>;

    /**
     * 检查工具是否可用
     * @param toolName 工具名称
     * @returns 可用状态
     */
    isToolAvailable(toolName: string): boolean;

    /**
     * 获取工具定义
     * @param toolName 工具名称
     * @returns 工具定义
     */
    getToolDefinition(toolName: string): ToolDefinition | null;
}

/**
 * 工具统计信息接口
 */
export interface ToolStats {
    totalTools: number;
    enabledTools: number;
    disabledTools: number;
    categories: Record<ToolCategory, number>;
    totalExecutions: number;
    averageExecutionTime: number;
    mostUsedTools: Array<{ name: string; count: number }>;
}